PIC24F
I2C™ Peripheral Module Library Help


Table Of Contents

1     Library Features. 4

2     Using Library Functions in Your Code. 4

3     Functions. 6

3.1        CloseI2C1 , CloseI2C2. 6

3.2        ConfigIntI2C1 , ConfigIntI2C2. 6

3.3        AckI2C1 , AckI2C2. 6

3.4        DataRdyI2C1, DataRdyI2C2. 7

3.5        IdleI2C1, IdleI2C2. 7

3.6        MastergetsI2C1, MastergetsI2C2. 7

3.7        MasterputsI2C1, MasterputsI2C2. 7

3.8        MasterReadI2C1, MasterReadI2C2. 8

3.9        MasterWriteI2C1, MasterWriteI2C2. 8

3.10       NotAckI2C1, NotAckI2C2. 8

3.11       OpenI2C1, OpenI2C2. 8

3.12       RestartI2C1, RestartI2C2. 9

3.13       SlavegetsI2C1, SlavegetsI2C2. 9

3.14       SlaveputsI2C1, SlaveputsI2C2. 10

3.15       SlaveReadI2C1, SlaveReadI2C2. 10

3.16       SlaveWriteI2C1 , SlaveWriteI2C2. 10

3.17       StartI2C1 , StartI2C2. 10

3.18       StopI2C1 , StopI2C2. 10

3.19       SlaveWaitForIntrI2C1 , SlaveWaitForIntrI2C2. 11

3.20       MasterWaitForIntrI2C1 , MasterWaitForIntrI2C2. 11

3.21       SlavegetcI2C1 , SlavegetcI2C2. 11

3.22       MastergetcI2C1 , MastergetcI2C2. 11

4     Macros. 11

4.1        EnableIntSI2C1 , EnableIntSI2C2. 11

4.2        DisableIntSI2C1 , DisableIntSI2C2. 11

4.3        EnableIntMI2C1 , EnableIntMI2C2. 12

4.4        DisableIntMI2C1 , DisableIntMI2C2. 12

4.5        SetPriorityIntSI2C1 , SetPriorityIntSI2C2. 12

4.6        SetPriorityIntMI2C1 , SetPriorityIntMI2C2. 12

4.7        mI2C1_MasterClearIntr() , mI2C2_MasterClearIntr() 12

4.8        mI2C1_SlaveClearIntr () , mI2C2_SlaveClearIntr () 12

 


1          Library Features

 

This peripheral library module:

 

·         Supports BYTE and WORD transmission and reception.

·         Incorporates multiple BYTE and WORD transmission and reception in a single function call.

·         Provides simple functions to read from and write to the buffers.

·         Provides simple interface macros to enable/disable interrupts.

 

2          Using Library Functions in Your Code

 

Library routine parameters can be constructed using either AND based mask or AND_OR based mask setting. For more information on these masks, see 16-bit Peripheral Libraries.

 

Examples of use for both the methods are below.

 

Example of Use ( AND mask )

 

#include<i2c.h>

void main(void )

{

  unsigned int config2, config1;

  unsigned char *wrptr;

  unsigned char tx_data[] = {'M','I','C','R','O','C','H','I','P','\0'};

  wrptr = tx_data;

  /* Baud rate is set for 100 Khz */

  config2 = 0x11;

  /* Configure I2C for 7 bit address mode */

  config1 = (I2C_ON & I2C_IDLE_CON & I2C_CLK_HLD &

             I2C_IPMI_DIS & I2C_7BIT_ADD &

             I2C_SLW_DIS & I2C_SM_DIS &

             I2C_GCALL_DIS & I2C_STR_DIS &

             I2C_NACK & I2C_ACK_DIS & I2C_RCV_DIS &

             I2C_STOP_DIS & I2C_RESTART_DIS &

             I2C_START_DIS);

  OpenI2C1(config1,config2);

  IdleI2C1();

  StartI2C1();

  /* Wait till Start sequence is completed */

  while(I2C1CONbits.SEN );

  /* Write Slave address and set master for transmission */

  MasterWriteI2C1(0xE);

  /* Wait till address is transmitted */

  while(I2C1STATbits.TBF);

  while(I2C1STATbits.ACKSTAT);

  /* Transmit string of data */

  MasterputsI2C1(wrptr);

  StopI2C1();

  /* Wait till stop sequence is completed */

  while(I2C1CONbits.PEN);

  CloseI2C1();

}


 

Example of Use ( AND_OR mask )

 

#define USE_AND_OR   /* To enable AND_OR mask setting */

#include<i2c.h>

 

void main(void )

{

  unsigned int config2, config1;

  unsigned char *wrptr;

  unsigned char tx_data[] = {'M','I','C','R','O','C','H','I','P','\0'};

  wrptr = tx_data;

  /* Baud rate is set for 100 Khz */

  config2 = 0x11;

  /* Configure I2C for 7 bit address mode */

  config1 = (I2C_ON | I2C_IDLE_CON | I2C_CLK_HLD |

            I2C_IPMI_DIS | I2C_7BIT_ADD |

            I2C_SLW_DIS | I2C_SM_DIS |

            I2C_GCALL_DIS | I2C_STR_DIS |

            I2C_NACK | I2C_ACK_DIS | I2C_RCV_DIS |

            I2C_STOP_DIS | I2C_RESTART_DIS |

            I2C_START_DIS);

  OpenI2C1(config1,config2);

  IdleI2C1();

  StartI2C1();

  /* Wait till Start sequence is completed */

  while(I2C1CONbits.SEN );

  /* Write Slave address and set master for transmission */

  MasterWriteI2C1(0xE);

  /* Wait till address is transmitted */

  while(I2C1STATbits.TBF);

  while(I2C1STATbits.ACKSTAT);

  /* Transmit string of data */

  MasterputsI2C1(wrptr);

  StopI2C1();

  /* Wait till stop sequence is completed */

  while(I2C1CONbits.PEN);

  CloseI2C1();

}

 


 

3          Functions

3.1         CloseI2C1 , CloseI2C2

 

Function Prototype

void CloseI2C1(void);

void CloseI2C2(void);

Include

i2c.h

Description

This function turns off the SPI module.

Arguments

None

Return Value

None

Remarks:

This function disables the I2C module and clears the Master and Slave Interrupt Enable and Flag bits.

3.2         ConfigIntI2C1 , ConfigIntI2C2

 

Function Prototype

ConfigIntI2C1(unsigned int config);

ConfigIntI2C2(unsigned int config);

Include

i2c.h

Description

This function configures the I2C Interrupt.

Arguments

config - I2C interrupt priority and enable/disable information as defined below:

I2C master Interrupt enable/disable

   MI2C_INT_ON

   MI2C_INT_OFF

I2C slave Interrupt enable/disable

   SI2C_INT_ON

   SI2C_INT_OFF

I2C master Interrupt priority

   MI2C_INT_PRI_7

   MI2C_INT_PRI_6

   MI2C_INT_PRI_5

   MI2C_INT_PRI_4

   MI2C_INT_PRI_3

   MI2C_INT_PRI_2

   MI2C_INT_PRI_1

   MI2C_INT_PRI_0

I2C slave Interrupt priority

   SI2C_INT_PRI_7

   SI2C_INT_PRI_6

   SI2C_INT_PRI_5

   SI2C_INT_PRI_4

   SI2C_INT_PRI_3

   SI2C_INT_PRI_2

   SI2C_INT_PRI_1

   SI2C_INT_PRI_0

Return Value

None

Remarks:

This function clears the Interrupt Flag bits, sets the interrupt priorities of master and slave and enables/disables the interrupt

3.3         AckI2C1 , AckI2C2

 

Function Prototype

void AckI2C1(void);

void AckI2C2(void);

Include

i2c.h

Description

Generates I2C bus Acknowledge condition.

Arguments

None

Return Value

None

Remarks:

This function generates an I2C bus Acknowledge condition.

3.4         DataRdyI2C1, DataRdyI2C2

 

Function Prototype

unsigned char DataRdyI2C1(void);

unsigned char DataRdyI2C2(void);

Include

i2c.h

Description

This function provides status back to user if I2CRCV register contain data.

Arguments

None

Return Value

This function returns ‘1’ if there is data in I2CRCV register; else return ‘0’ which indicates no data in I2CRCV register.

Remarks:

This function determines if there is any byte to read from I2CRCV register.

3.5         IdleI2C1, IdleI2C2

 

Function Prototype

void IdleI2C1(void);

void IdleI2C2(void);

Include

i2c.h

Description

This function generates Wait condition until I2C bus is Idle.

Arguments

None

Return Value

None

Remarks:

This function will be in a wait state until Start Condition Enable bit, Stop Condition Enable bit, Receive Enable bit, Acknowledge Sequence Enable bit of I2C Control register and Transmit Status bit I2C Status register are clear. The IdleI2C function is required since the hardware I2C peripheral does not allow for spooling of bus sequence. The I2C peripheral must be in Idle state before an I2C operation can be initiated or write collision will be generated.

3.6         MastergetsI2C1, MastergetsI2C2

 

Function Prototype

unsigned int MastergetsI2C1(unsigned int length,

  unsigned char *rdptr, unsigned int i2c_data_wait);

unsigned int MastergetsI2C2(unsigned int length,

  unsigned char *rdptr, unsigned int i2c_data_wait);

Include

i2c.h

Description

This function reads predetermined data string length from the I2C bus.

Arguments

length - Number of bytes to read from I2C device.

rdptr - Character type pointer to RAM for storage of data read from I2C device

i2c_data_wait - This is the time-out count for which the module has to wait before return. If the time-out count is ‘N’, the actual time out would be about (20 * N – 1) instruction cycles.

Return Value

This function returns ‘0’ if all bytes have been sent or number of bytes read from I2C bus if its not able to read the data with in the specified i2c_data_wait time out value

Remarks:

This routine reads a predefined data string from the I2C bus.

3.7         MasterputsI2C1, MasterputsI2C2

 

Function Prototype

char MasterputsI2C1(unsigned char *wrptr);

char MasterputsI2C2(unsigned char *wrptr);

Include

i2c.h

Description

This function is used to write out a data string to the I2C bus.

Arguments

wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device.

Return Value

This function returns ‘-3‘ if a write collision occurred. This function returns ‘0’ if the null character was reached in data string.

Remarks:

This routine reads a predefined data string from the I2C bus.

3.8         MasterReadI2C1, MasterReadI2C2

 

Function Prototype

char MasterputsI2C1(unsigned char *wrptr);

char MasterputsI2C2(unsigned char *wrptr);

Include

i2c.h

Description

This function is used to read a single byte from I2C bus

Arguments

wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device.

Return Value

The return value is the data byte read from the I2C bus.

Remarks:

This function reads in a single byte from the I2C bus.

This function performs the same function as MastergetcI2C.

3.9         MasterWriteI2C1, MasterWriteI2C2

 

Function Prototype

char MasterWriteI2C1(unsigned char data_out);

char MasterWriteI2C2(unsigned char data_out);

Include

i2c.h

Description

This function is used to write out a single data byte to the I2C device.

Arguments

data_out - A single data byte to be written to the I2C bus device.

Return Value

This function returns ‘-1‘ if there was a write collision else it returns a ‘0‘.

Remarks:

This function reads in a single byte from the I2C bus.

This function performs the same function as MastergetcI2C.

3.10     NotAckI2C1, NotAckI2C2

 

Function Prototype

void NotAckI2C1(void);

void NotAckI2C2(void);

Include

i2c.h

Description

Generates I2C bus Not Acknowledge condition.

Arguments

None

Return Value

None

Remarks:

This function generates an I2C bus Not Acknowledge condition.

3.11     OpenI2C1, OpenI2C2

 

Function Prototype

void OpenI2C1(unsigned int config1,

   unsigned int config2);

void OpenI2C2(unsigned int config1,

   unsigned int config2);

Include

i2c.h

Description

Configures the I2C module

Arguments

config1 - This contains the parameter to configure the I2CCON register

I2C Enable bit

   I2C_ON

   I2C_OFF

I2C Stop in Idle Mode bit

   I2C_IDLE_STOP

   I2C_IDLE_CON

SCL Release Control bit

   I2C_CLK_REL

   I2C_CLK_HLD

Intelligent Peripheral Management Interface Enable bit

   I2C_IPMI_EN

   I2C_IPMI_DIS

10-bit Slave Address bit

   I2C_10BIT_ADD

   I2C_7BIT_ADD

Disable Slew Rate Control bit

   I2C_SLW_DIS

   I2C_SLW_EN

SMBus Input Level bits

   I2C_SM_EN

   I2C_SM_DIS

General Call Enable bit

   I2C_GCALL_EN

   I2C_GCALL_DIS

SCL Clock Stretch Enable bit

   I2C_STR_EN

   I2C_STR_DIS

Acknowledge Data bit

   I2C_ACK

   I2C_NACK

Acknowledge Sequence Enable bit

   I2C_ACK_EN

   I2C_ACK_DIS

Receive Enable bit

   I2C_RCV_EN

   I2C_RCV_DIS

Stop Condition Enable bit

   I2C_STOP_EN

   I2C_STOP_DIS

Repeated Start Condition Enable bit

   I2C_RESTART_EN

   I2C_RESTART_DIS

Start Condition Enable bit

   I2C_START_EN

   I2C_START_DIS

 

config2 - computed value for the baud rate generator

Return Value

None

Remarks:

This function configures the I2C Control register and I2C Baud Rate Generator register

3.12     RestartI2C1, RestartI2C2

 

Function Prototype

void RestartI2C1(void);

void RestartI2C2(void);

Include

i2c.h

Description

Generates I2C Bus Restart condition.

Arguments

None

Return Value

None

Remarks:

This function generates an I2C Bus Restart condition.

3.13     SlavegetsI2C1, SlavegetsI2C2

 

Function Prototype

unsigned int SlavegetsI2C1(unsigned char *rdptr,

   unsigned int i2c_data_wait);

unsigned int SlavegetsI2C2(unsigned char *rdptr,

   unsigned int i2c_data_wait);

Include

i2c.h

Description

This function reads pre-determined data string length from the I2C bus.

Arguments

rdptr - Character type pointer to RAM for storage of data read from I2C device.

i2c_data_wait - This is the time-out count for which the module has to wait before return.

If the time-out count is ‘N’, the actual time out would be about (20*N - 1) instruction cycles.

Return Value

Returns the number of bytes received from the I2C bus.

Remarks:

This routine reads a predefined data string from the I2C bus.

3.14     SlaveputsI2C1, SlaveputsI2C2

 

Function Prototype

unsigned int SlaveputsI2C1(unsigned char *wrptr);

unsigned int SlaveputsI2C2(unsigned char *wrptr);

Include

i2c.h

Description

This function is used to write out a data string to the I2C bus.

Arguments

wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device.

Return Value

This function returns ‘0’ if the null character was reached in the data string.

Remarks:

This routine writes a data string out to the I2C bus until a null character is reached

3.15     SlaveReadI2C1, SlaveReadI2C2

 

Function Prototype

unsigned char SlaveReadI2C1(void);

unsigned char SlaveReadI2C2(void);

Include

i2c.h

Description

This function is used to read a single byte from the I2C bus.

Arguments

None

Return Value

The return value is the data byte read from the I2C bus.

Remarks:

This function reads in a single byte from the I2C bus. This function performs the same function as SlavegetcI2C.

3.16     SlaveWriteI2C1 , SlaveWriteI2C2

 

Function Prototype

void SlaveWriteI2C1(unsigned char data_out);

void SlaveWriteI2C2(unsigned char data_out);

Include

i2c.h

Description

This function is used to write out a single byte to the I2C bus.

Arguments

data_out - A single data byte to be written to the I2C bus device.

Return Value

None

Remarks:

This function writes out a single data byte to the I2C bus device. This function performs the same function as SlaveputcI2C.

3.17     StartI2C1 , StartI2C2

 

Function Prototype

void StartI2C1(void);

void StartI2C2(void);

Include

i2c.h

Description

Generates I2C Bus Start condition.

Arguments

None

Return Value

None

Remarks:

This function generates an I2C Bus Start condition.

3.18     StopI2C1 , StopI2C2

 

Function Prototype

void StopI2C1(void);

void StopI2C2(void);

Include

i2c.h

Description

Generates I2C Bus Stop condition.

Arguments

None

Return Value

None

Remarks:

This function generates a I2C Bus Stop condition.

3.19     SlaveWaitForIntrI2C1 , SlaveWaitForIntrI2C2

 

Function Prototype

void SlaveWaitForIntrI2C1(void);

void SlaveWaitForIntrI2C2(void);

Include

i2c.h

Description

This routine will wait for Slave interrupt request and then clear interrupt Flag.

Arguments

None

Return Value

None

Remarks:

None

3.20     MasterWaitForIntrI2C1 , MasterWaitForIntrI2C2

 

Function Prototype

void MasterWaitForIntrI2C1(void);

void MasterWaitForIntrI2C2(void);

Include

i2c.h

Description

This routine will wait for Master interrupt request and then clear interrupt Flag.

Arguments

None

Return Value

None

Remarks:

None

3.21     SlavegetcI2C1 , SlavegetcI2C2

 

Include

i2c.h

Description

This function is identical to SlaveReadI2C1 and SlaveReadI2C2, i.e., #define SlavegetcI2C1 SlaveReadI2C1 in i2c.h.

3.22     MastergetcI2C1 , MastergetcI2C2

 

Include

i2c.h

Description

This function is identical to MastergetcI2C1 and MastergetcI2C2, i.e., #define MastergetcI2C1 MasterReadI2C1 in i2c.h.

4          Macros

4.1         EnableIntSI2C1 , EnableIntSI2C2

 

Macro

EnableIntSI2C1

EnableIntIS2C2

Include

i2c.h

Description

Macro enables I2C Slave Interrupt

Arguments

None

Remarks

None

 

4.2         DisableIntSI2C1 , DisableIntSI2C2

 

Macro

DisableIntSI2C1

DisableIntIS2C2

Include

i2c.h

Description

Macro disables I2C Slave Interrupt

Arguments

None

Remarks

None

4.3         EnableIntMI2C1 , EnableIntMI2C2

 

Macro

EnableIntMI2C1

EnableIntIM2C2

Include

i2c.h

Description

Macro enables I2C Master Interrupt

Arguments

None

Remarks

None

4.4         DisableIntMI2C1 , DisableIntMI2C2

 

Macro

DisableIntMI2C1

DisableIntIM2C2

Include

i2c.h

Description

Macro disables I2C Master Interrupt

Arguments

None

Remarks

None

4.5         SetPriorityIntSI2C1 , SetPriorityIntSI2C2

 

Macro

SetPriorityIntSI2C1

SetPriorityIntSI2C2

Include

i2c.h

Description

Macro sets the priority level for I2C Salve interrupt.

Arguments

priority - This input parameter is the level of interrupt priority.

Remarks

None

4.6         SetPriorityIntMI2C1 , SetPriorityIntMI2C2

 

Macro

SetPriorityIntMI2C1

SetPriorityIntMI2C2

Include

i2c.h

Description

Macro sets the priority level for I2C Master interrupt.

Arguments

priority - This input parameter is the level of interrupt priority.

Remarks

None

4.7         mI2C1_MasterClearIntr() , mI2C2_MasterClearIntr()

 

Macro

mI2C1_MasterClearIntr()

mI2C2_MasterClearIntr()

Include

i2c.h

Description

This macro clears the I2C Master interrupt flag

Arguments

None

Remarks

None

4.8         mI2C1_SlaveClearIntr () , mI2C2_SlaveClearIntr ()

 

Macro

mI2C1_SlaveClearIntr ()

mI2C2_SlaveClearIntr()

Include

i2c.h

Description

This macro clears the I2C Slave interrupt flag

Arguments

None

Remarks

None